.TH "MAGENTA" "8" "Mar 23, 2009" "" ""
.SH "NAME"
magenta \- an iptables preprocessor
.SH "SYNOPSIS"
\fBmagenta\fR [\fB\-\-version\fR] [\fB\-\-debug\fR]
.br
.SH "OPTIONS"
.TP
.B \-\-version
magenta prints its version and exits.
.TP
.B \-\-debug
magenta will print the commands to be executed instead of actually executing them.
.SH "DESCRIPTION"
magenta is a bash script which aim is to simplify and clean the syntax of iptables
and to provide some "infrastructure" for the firewall rules.
.P
Normally it is installed to be run at boot time just before the networking is brought up.
As all init scripts, magenta's take either \fBstart\fR or \fBstop\fR argument, so there
are two "states" of the firewall, let's call them "closed" and "opened". In the closed
state the firewall is configured to deny everything except the bare minimum; in the
opened state the firewall is configured to allow some valid traffic to pass through.
Note that magenta can not delete rules, so design your rulesets like this:
.TP
.B closed
flushes everything from every table and every chain
.br
explicitely sets all the policies
.br
adds some initial rules
.TP
.B opened
adds all other rules
.P
magenta takes a snapshot of the iptables state at the very early stage, and tries to restore it
if anything goes wrong, so in general there should be no trouble if your ruleset contains an error.
.P
Note that magenta is not a firewall of any kind, it parses the rules and feeds them
to iptables, so it's still a good idea to be familiar with what iptables do
and how the packets flow inside the kernel to be able to construct your ruleset.
.P
The \fBmcedit\fR's syntax highlighting of the files with magenta rules is also a nice little feature
(to achieve this either name the files as \fB*.magenta\fR or begin them with "\fB##magenta\fR").
.P
In most cases you should start magenta as root.
.SH "RULES"
.B magenta
reads stdin for the rules. Each line is considered a rule if it is not empty or does not start with
.B #
character. As the lines are read with bash's
.B read
command, you can end the line with a backslash ("\\") to escape the line break. For example two lines:
.RS
allow icmp \\
.br
in on lo
.RE
will be treated as one line:
.RS
allow icmp in on lo
.RE
.SH "RULE SYNTAX"
Rules are constructed of instructions and their parameters. In general, the order is not significant,
but there are some exceptions (\fBon\fR and \fBports\fR).
.P
Instructions define what packets to match and what to do with those that matched.
.SS "Target instructions"
.TP
.B allow
let the packet through
.TP
.B deny
throw the packet out
.TP
.B reject
like \fBdeny\fR, but also send back some kind of notification that the packet was dropped
.TP
.BR "rewrite\-to" " <address> [\fBports\fR <ports>]"
rewrite the source or destination address of the packet (NAT)
.P
There are two special "addresses" that may be passed to \fBrewrite\-to\fR instruction:
.TP
.B (same)
if you need to only rewrite ports, not the address
.TP
.B (self)
if you need to rewrite address to the one of host itself
.br
Note, that there is no logic to detect this address, instead there will be
\fBMASQUERADE\fR instead of \fBSNAT\fR and \fBREDIRECT\fR instead of \fBDNAT\fR (man iptables).
.P
Exactly one target should always be present.
.SS "Direction instructions"
.TP
.BR "in" " [\fBon\fR [\fBnot\fR] <interface>]"
match the incoming packets or rewrite destination address
.TP
.BR "out" " [\fBon\fR [\fBnot\fR] <interface>]"
match the outcoming packets or rewrite source address
.P
There should be at least one direction instruction. If both are specified, then the packet
will be matched when it passes through the host, that is when the host routes the packet.
.SS "Address instructions"
.TP
.BR "from" " [\fBnot\fR] <address> [\fBports\fR [\fBnot\fR] <ports>]"
match the source address of a packet
.TP
.BR "to" " [\fBnot\fR] <address> [\fBports\fR [\fBnot\fR] <ports>]"
match the destination address of a packet
.P
There is a special "address" \fB(any)\fR that can be passed to [from]
or [to] instruction. It is useful if you need to match the packet against ports only.
.P
Keep in mind that ports do only make sense with \fBtcp\fR or \fBudp\fR protocols.
.SS "Protocol instructions"
.TP
.B tcp
same as "proto tcp"
.TP
.B udp
same as "proto udp"
.TP
.B icmp
same as "proto icmp"
.TP
.BR "proto" " [\fBnot\fR] <protocol>"
defines a protocol to match (man iptables)
.SS "State instructions"
.TP
.B new
will become "\-\-match state \-\-state NEW"
.TP
.B established
will become "\-\-match state \-\-state ESTABLISHED"
.TP
.B related
will become "\-\-match state \-\-state RELATED"
.TP
.B established\-or\-related
will become "\-\-match state \-\-state ESTABLISHED,RELATED"
.P
These instructions deal with connection states, please see iptables man page for explanation.
.SS "Other instructions"
.TP
.B random
if a port range is specified for rewrite, allocate them in random order
.TP
.B options
allows you to add arbitrary iptables options: the text from this instruction till the end of line
is passed to iptables intact (this instruction also disables most of sanity checks of magenta)
.TP
.B #
the text from this instruction till the end of line is considered a comment and is passed
to iptables as such.
.br
Note, that there should be a space or a tab before and after the \fB#\fR character
.SH "DEPENDENCIES"
As magenta is implemented in \fBbash\fR, it does obviously need it, version 3.1 or higher.
.br
\fBiptables\fR, \fBiptables\-save\fR and \fBiptables\-restore\fR are also required.
.SH "BUGS"
There is a bug in \fBiptables\-save\fR that makes \fBiptables\-restore\fR
to fail if there are any double quotes inside an option value. In short,
avoid putting double quotes in comments.
.P
(http://bugs.debian.org/cgi\-bin/bugreport.cgi?bug=519584)
.SH "FILES"
.B "/etc/network/on.magenta"
.br
.B "/etc/network/off.magenta"
.SH "SEE ALSO"
.BR "iptables" " (8)"
.P
If you need any additional clarification, try looking at the example rules in \fB/use/share/doc/magenta\fR
directory, then check \fBiptables\fR man page again, and as a last resort (or first if you have some skill
with \fBbash\fR scripting) try looking inside the \fBmagenta\fR itself.
.SH "AUTHORS"
stronny <stronny@celestia.ru>
.SH "LICENSE"
This software is public domain.
